
namespace Needle.Core.Lifetime {

    /// <summary>
    /// Provides an interface to track an instance's lifetime.
    /// </summary>
    public interface IReference {
        /// <summary>
        /// The instance to track or null if the reference is not valid.    
        /// </summary>
        object Target { get;}
        /// <summary>
        /// True if the target is still valid , false otherwise.
        /// </summary>
        /// <remarks>
        /// Due to differences in implementation of IReference the
        /// correct way of determining the Target and its validity is:
        /// <code>
        /// object target = reference.Target;
        /// if (reference.IsValid &amp;&amp; target != null){
        ///     // target is valid here
        /// }
        /// </code>
        /// </remarks>
        bool IsValid { get;}

    }

}
